<!-- -*- sgml -*- -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<title>Jade - James' DSSSL Engine</title>
<body bgcolor="#ffffff">
<h1>Jade - James' DSSSL Engine</h1>

<h2>Contents</h2>
<UL>
<LI><A HREF="#whatis">What is Jade?</A>
<LI><A HREF="#copyright">Copyright</A>
<LI><A HREF="#getting">Getting Jade</A>
<LI><A HREF="#building">Building Jade</A>
<UL>
<LI><A HREF="#building-win32">Win32</A>
<LI><A HREF="#building-unix">Unix</A>
</UL>
<LI><A HREF="#using">Using Jade</A>
<LI><A HREF="#extensions">Jade Extensions</A>
<LI><A HREF="#limitations">Current Jade Limitations</A>
<LI><A HREF="#backends">Backends</A>
<UL>
<LI><A HREF="#backend-rtf">RTF</A>
<LI><A HREF="#backend-fot">XML Flow Object Tree</A>
<LI><A HREF="TeX.htm">TeX</A>
<LI><A HREF="mif.htm">MIF</A>
<LI><A HREF="transform.htm">SGML Transformation</A>
</UL>
<LI><A HREF="#source">Reading the Jade Sources</A>
<LI><A HREF="#bugs">Reporting Bugs in Jade</A>
<LI><A HREF="#contribute">Contributing to Jade</A>
</UL>

<h2><A NAME=whatis>What is Jade?</A></h2>
<p>
Jade is an implementation of the DSSSL style language.
The current version is 1.2.1.
<p>
For general information about DSSSL, see my <a
href="http://www.jclark.com/dsssl/">DSSSL page</A>.
<p>
You can discuss Jade and get help from other users on DSSSList, the
DSSSL Users' Mailing List.  I will announce new versions of Jade on
DSSSList.  To subscribe send mail to <A
HREF="mailto:majordomo@mulberrytech.com">majordomo@mulberrytech.com</A>
with "subscribe dssslist" as the body of your message.  To subscribe
to the digest instead, the body should be "subscribe dssslist-digest".
The list is <A
HREF="http://www.mulberrytech.com/dsssl/dssslist/archive">archived</A>.
<p>
Jade includes the following components:
<UL>
<LI>
An abstract interface to groves.
This is designed to be implementable on top of a database,
in addition to simple in-memory implementations.
<P>
The source is in the grove directory.
<LI>
An in-memory implementation of this interface built with SP.
<P>
This is
multi-threaded (on Win32 only at the moment): the grove can be
accessed before it is complete and access to a property of a node will
block until that property becomes available.
This allows the style engine to produce output before
it has read all the document.
<P>
The source is in the spgrove directory.
<LI>
A style engine that implements the DSSSL style language.  This depends
on the grove interface, but not the spgrove implementation of that
interface.  It depends on SP for the parsing of DSSSL specifications.
The style engine relies on a backend to actually do the formatting.
The backend interface is designed to accomodate browsers as well as
command-line applications, but it does not currently provide
interfaces that would allow for editing either of SGML documents or
DSSSL specs.
<P>
The source is in the style directory.
<LI>
A command-line application, <CODE>jade</CODE>, that combines the style
engine with the spgrove grove interface and five backends:
<UL>
<LI>
A backend that generates an XML representation of the flow
object tree.
<LI>
A backend that generates RTF.  This has been tested with
Microsoft Word 97 and Microsoft's free
<A HREF="http://www.microsoft.com/word/internet/viewer/">Word Viewer 97</A>.
Previous versions were tested with Word 95 and Word Viewer 7.1.
<LI>
A backend that generates TeX.
<LI>
A backend that generates MIF.
<LI>
A backend that generates SGML.
This is used in conjunction with non-standard flow object classes
to generate SGML, thus allowing Jade to be used
for SGML transformations.
</UL>
<P>
The source is in the jade directory.
</UL>

<h2><A NAME=copyright>Jade Copyright</A></h2>
<p>
Jade is licensed under the same <A HREF="copying.txt">terms</A> as SP.  This
imposes almost no restrictions even for commercial use.
<P>
If you do use Jade in a commercial product, I would ask you, as a
courtesy, to let me know about it and acknowledge the use of Jade.

<h2><A NAME=getting>Getting Jade</A></h2>
<p>
If you're using Windows 95 or Windows NT, then you all you need is in the <A
HREF="ftp://ftp.jclark.com/pub/jade/jadew1_2_1.zip">binary distribution</A>.
<P>
Otherwise you will need to build it yourself from source. The
Jade sources are available in two forms:

<DL>
<DT>
<A HREF="ftp://ftp.jclark.com/pub/jade/jade1_2_1.zip">Windows
distribution</A></DT>
<DD>
This is a ZIP file.  The sources use CR/LF delimited lines.  After
getting this create a new directory and then unpack the sources file
in this directory.  You must use an unzip that preserves long
filenames, such as WinZip 6.1.  You should also make sure that your
unzip preserves the case of filenames; this requires using a
<SAMP>-U</SAMP> option with some versions of unzip. You should also
ensure that the unzip preserves the directories. If you want to use
this on Unix, you must unpack using <SAMP>unzip -a</SAMP> since the
sources in the Windows distribution use CR/LF delimited lines.
<DD>
<DT>
<A href="ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz">Unix
distribution</A></DT>
<DD>
This is a gzipped, tar file.  The sources use LF delimited
lines. Unpack this using gunzip and tar.
</DL>

<p>
The distributions include the sources for a compatible version of SP
(which may be different from the latest released version of SP).

<h2><A NAME=building>Building Jade</A></h2>

<h3><A NAME=building-win32>Win32</A></h3>
<p>
Only Microsoft Visual C++ 6.0 is supported.  To build using the Visual
Studio GUI, open the workspace <code>jade.dsw</code> and build the
<code>Win32&nbsp;Release</code> configuration of the <code>all</code>
project.  To build on the command line, ensure that the directory
containing <code>msdev</code> is in your path, typically by executing
the command:
<pre>
path C:/Program Files/Microsoft Visual Studio/Common/MSDev98/Bin;%path%
</pre>
<p>
then run the command:
<pre>
msdev jade.dsw /make "all - Win32 Release"
</pre>

<h3><A NAME=building-unix>Unix</A></h3>
<p>
The following compilers should work:
<ul>
<li>egcs 1.0.2
<li>gcc 2.8.1
<li>gcc 2.7.2
</ul>
<p>Only the first has been tested by me.
<p>
If you use gcc 2.7.2 with -O on an x86 processor you must use
-fno-strength-reduce. gcc 2.7.2.1 fixes this problem.
<p>
Edit <code>Makefile</code>, then build with <code>make</code>.  Note
that you must use -DSP_MULTI_BYTE. If you plan to do any development,
also do <code>make depend</code>.
<p>
Alternatively you can build using the <a
HREF="autoconf.htm">experimental autoconf support</a>.

<h2><A NAME=using>Using Jade</A></h2>
<P>
Add the directory containing the jade binary to your path,
change directory to the dsssl directory, and do
<pre>
jade demo.sgm
</pre>
<P>
If everything is working, there should be a well-formed
XML file <code>demo.fot</code> created.
<P>
The system identifier of the document to be processed is specified as
an argument to Jade.  If this is omitted, standard input will be read.
<P>
Jade determines the system identifier for the DSSSL specification
as follows:
<OL>
<LI>
If the <CODE>-d</CODE> option is specified, it will use the
argument as the system identifier.
<LI>
Otherwise, it will look for processing instructions in the prolog of
the document. Two kinds of processing instruction are recognized:
<DL>
<DT>
<CODE>&lt;?stylesheet href="<VAR>sysid</VAR>" type="text/dsssl"&gt;</CODE>
<DD>
The system data of the processing instruction is parsed like an SGML
start-tag.  It will be parsed using the reference concrete syntax
whatever the actual concrete syntax of the document.  The name that
starts the processing instruction can be either
<CODE>stylesheet</CODE>, <CODE>xml-stylesheet</CODE> or
<CODE>xml:stylesheet</CODE>.  The processing instruction will be
ignored unless the value of the <CODE>type</CODE> attribute is one of
<CODE>text/dsssl</CODE>, <CODE>text/x-dsssl</CODE>,
<CODE>application/dsssl</CODE>, or <CODE>application/x-dsssl</CODE>.
The value of <CODE>href</CODE> attribute is the system identifier of
the DSSSL specification.
<DT>
<CODE>&lt;?dsssl <VAR>sysid</VAR>&gt;</CODE>
<DD>
The system identifier is the portion of the system data of the
processing instruction following the initial name and any whitespace.
</DL>
<P>
Although the processing instruction is only recognized in the
prolog, it need not occur in the document entity.
For example, it could occur in a DTD.
The system identifier will be interpreted relative to where the
the processing instruction occurs.
<LI>
Otherwise, it will use the system identifier of the document
with any extension changed to <CODE>.dsl</CODE>.
</OL>
<P>
A DSSSL specification document can contain more than one
style-specification.  
If the system identifier of the DSSSL specification is followed
by <CODE>#<VAR>id</VAR></CODE>,
then jade will use the style-specification whose unique identifier is
<CODE><VAR>id</VAR></CODE>.
This is allowed both with the <CODE>-d</CODE> option and with
the processing instructions.
<P>
The DSSSL specification must be an SGML document
conforming to the DSSSL architecture.
For an example, see <CODE>dsssl/demo.dsl</CODE>.
<P>
Jade supports the following options
in addition to the normal SP options:
<DL>
<DT>
<CODE>-d <VAR>dsssl_spec</VAR></CODE>
<DD>
This specifies that <CODE><VAR>dsssl_spec</VAR></CODE> is the system
identifier of the DSSSL specification to be used.
<DT>
<CODE>-G</CODE>
<DD>
Debug mode.
When an error occurs in the evaluation of an expression,
Jade will display a stack trace.
Note that this disables tail-call optimization.
<DT>
<CODE>-t <VAR>output_type</VAR></CODE>
<DD>
<CODE><VAR>output_type</VAR></CODE> specifies the type of output as follows:
<DL COMPACT>
<DT>
<CODE>fot</CODE>
<DD>
An XML representation of the flow object tree
<DT>
<CODE>rtf</CODE>
<CODE>rtf-95</CODE>
<DD>
Microsoft's Rich Text Format.
<CODE>rtf-95</CODE> produces output optimized for Word 95 rather than Word 97.
<DT>
<CODE>tex</CODE>
<DD>
TeX
<DT>
<CODE>sgml</CODE>
<DD>
SGML (used for SGML-to-SGML transformations)
<DT>
<CODE>xml</CODE>
<DD>
XML (used for SGML-to-XML transformations)
</DL>
<DT>
<CODE>-o <VAR>output_file</VAR></CODE>
<DD>
Write output to <CODE><VAR>output_file</VAR></CODE> instead of
the default.
The default filename is the name of the last input file with its
extension replaced by the name of the type of output.
If there is no input filename, then the extension is added onto
<CODE>jade-out</CODE>.
<DD>
<DT>
<CODE>-V <VAR>variable</VAR></CODE>
<DD>
This is equivalent to doing
<PRE>
(define <VAR>variable</VAR> #t)
</PRE>
except that this definition will take priority over any definition of
<VAR>variable</VAR> in a style-sheet.
</DL>
<P>
Jade ignores the <SAMP>SP_CHARSET_FIXED</SAMP> and
<SAMP>SP_SYSTEM_CHARSET</SAMP> environment variables and always uses
Unicode as its internal character set, as if
<SAMP>SP_CHARSET_FIXED</SAMP> was 1 and <SAMP>SP_SYSTEM_CHARSET</SAMP>
was unset.  Thus only the <SAMP>SP_ENCODING</SAMP> environment variable
is relevant to Jade's handling of character sets.

<h2><A NAME="extensions">Jade Extensions</A></h2>
<p>
The following external procedures are available.  These external
procedures are defined by a prototype in the same manner as in the
standard.  To use one of these external procedures, you must make use
of the standard <code>external-procedure</code> procedure, using a
public identifier of <code>"UNREGISTERED::James
Clark//Procedure::<var>name</var>"</code> where
<code><var>name</var></code> is the name given here, typically by
including the following in the DSSSL specification:
<pre>
(define <var>name</var>
  (external-procedure "UNREGISTERED::James Clark//Procedure::<var>name</var>"))
</pre>
<p>
Note that <code>external-procedure</code> returns <code>#f</code> if
it doesn't know about the specified public identifier.  You can use
this to enable your DSSSL specifications to work gracefully with other
implementations which do not support these extensions.

<h3>Debugging</h3>

<pre>
(debug <var>obj</var>)
</pre>
<p>
Generates a message including the value of <code><var>obj</var></code> and
then returns <code><var>obj</var></code>.

<h3>Simple-page-sequence header/footer control</h3>

<pre>
(if-first-page <var>sosofo1</var> <var>sosofo2</var>)
</pre>
<p>
This can be used only in the specification of the value of one of the
header/footer characteristics of simple-page-sequence.  It returns a
sosofo that will display as <code><var>sosofo1</var></code> if the
page is the first page of the simple-page-sequence and as
<code><var>sosofo2</var></code> otherwise.

<pre>
(if-front-page <var>sosofo1</var> <var>sosofo2</var>)
</pre>
<p>
This can be used only in the specification of the value of one of the
header/footer characteristics of simple-page-sequence.  It returns a
sosofo that will display as <code><var>sosofo1</var></code> if the
page is a front (ie recto, odd-numbered) page and as
<code><var>sosofo2</var></code> if it is a back (ie verso,
even-numbered) page

<h3>Numbering</h3>

<pre>
(all-element-number)
(all-element-number <var>osnl</var>)
</pre>
<p>
This is the same as <CODE>element-number</CODE> except it counts
elements with any generic identifier.  If <CODE><VAR>osnl</VAR></CODE>
is not an element returns #f, otherwise returns 1 plus the number of
elements that started before <CODE><VAR>osnl</VAR></CODE>.  This
provides an efficient way of creating a unique identifier for any
element in a document.

<h3>External entity access</h3>

<pre>
(read-entity <var>string</var>)
</pre>
<p>
This returns a string containing the contents of the external entity
with system identifier <code><var>string</var></code>.  This should be
used only for textual entities (CDATA and SDATA), and not for binary
entities (NDATA).

<h2><A NAME="limitations">Current Jade Limitations</A></h2>
<p>
This section describes the limitations of the front-end (the general-purpose
DSSSL engine): each backend also has its own limitations.
<P>
Only the DSSSL Online subset of DSSSL is implemented
with the following additions (all part of full DSSSL)
<UL>
<LI>the math flow objects
<LI>lambda (including #!key)
<LI>let, letrec, let* and named let
<LI>quasiquotation
<LI>node-list-first
<LI>node-list-rest
<LI>node-property
<LI>sgml-parse
<LI>children
<LI>descendants
<LI>attributes
<LI>follow
<LI>preced
<LI>data
<LI>select-elements
<LI>select-by-class
<LI>node-list-no-order
<LI>node-list=?
<LI>node-list?
<LI>node-list
<LI>node-list-map
<LI>node-list-length
<LI>node-list-ref
<LI>node-list-reverse
<LI>named-node-list?
<LI>named-node
<LI>named-node-list-names
<LI>named-node-list-normalize
<LI>process-node-list
<LI>node-list-address (argument restricted to a singletion node-list)
<LI>element-with-id
<LI>empty-node-list
</UL>
<P>
Note that only inherited characteristics that are applicable to some
supported flow object can be specified.
<P>
Jade supports only a single, fixed grove plan which comprises the
following modules:
<UL>
<li>baseabs
<li>prlgabs0
<li>instabs
<li>basesds0
<li>instsds0
<li>subdcabs
</UL>

<h3>Character/glyph handling</h3>
<P>
It only supports a single pre-defined character repertoire.  A
character name of the form <CODE>U-<VAR>XXXX</VAR></CODE> where
<CODE><VAR>XXXX</VAR></CODE> are four upper-case hexadecimal digits,
is recognized as referring to the Unicode character with that code.
For many characters, it is also
possible to use the ISO/IEC 10646 name in lower-case with words
separated by hyphens.
<P>
Some common SDATA entity names from the ISO entity sets are recognized
and mapped to characters.  In addition an SDATA entity name of the
form <CODE>U-<VAR>XXXX</VAR></CODE>, where
<CODE><VAR>XXXX</VAR></CODE> are four upper-case hexadecimal digits,
is mapped to the Unicode character with that code.
<P>
Jade does not make use of any of the declaration architectural forms
related to characters and glyphs.
<P>
The following style language declarations (as well as the non-DSSSL
Online declarations) are ignored:
<PRE>
declare-char-characteristic+property
declare-char-property
add-char-properties
define-language
declare-default-language
</PRE>

<h3>Validation</h3>
<P>
Several things that it would be desirable to have checked aren't
checked:
<ul>
<li>
When the allowed value of an inherited characteristic is a
symbol, jade checks only that the value is a symbol that is
allowed as the value of some characteristic; #t and #f are
treated as a special kind of symbol in this case.
<li>
Jade doesn't check whether a flow object is occurring in a context
where it is allowed.
<li>
Jade does not prevent flow objects being attached to the
principal port of a flow object when the flow object shouldn't
have a principal port.
<li>
Most type-checking is done at run-time not compile-time.
<li>
Jade does not check for non-inherited characteristics that are
required to be specified.
<li>
It doesn't check that optional features that have been used were
declared in the features form.
</ul>

<h3>Other limitations</h3>
<P>
The following primitives are just stubs:
<DL>
<DT>
<CODE>char-script-case</CODE>
<DD>
Always returns last argument.
<DT>
<CODE>char-property</CODE>
<DD>
Always returns #f or specified default value.
<DT>
<CODE>address-visited?</CODE>
<DD>
Always returns #f.
</DL>


<h2><A NAME=backends>Backends</A></h2>
<h3><A NAME=backend-rtf>RTF backend</A></h3>
<P>
Only the following flow object classes are implemented:
<DL>
<DT>
<CODE>sequence</CODE>
<DT>
<CODE>character</CODE>
<DT>
<CODE>paragraph</CODE>
<DT>
<CODE>paragraph-break</CODE>
<DT>
<CODE>line-field</CODE>
<DD>
Only at the beginning of a paragraph.
<DT>
<CODE>display-group</CODE>
<DT>
<CODE>simple-page-sequence</CODE>
<DT>
<CODE>score</CODE>
<DD>
Only type <CODE>after</CODE> and <CODE>through</CODE>
<DT>
<CODE>rule</CODE>
<DD>
Only horizontal orientation.
Rules only show up in Page Layout View.
<DT>
<CODE>box</CODE>
<DD>
Changing indentation inside a box will not work.
<DT>
<CODE>leader</CODE>
<DD>
The content of the flow object is ignored: a dotted leader will always be
used.  The specified length is ignored: it always fills out the line.
<DT>
<CODE>external-graphic</CODE>
<DD>
On Windows platforms, this can be used to embed OLE objects, by making
the the value of the <CODE>notation-system-id:</CODE> a formal system
identifier whose storage manager is <CODE>CLSID</CODE> and whose
storage object identifier is the COM CLSID (including surrounding
braces). The system identifier may also be just
<CODE>&lt;CLSID&gt;</CODE> (that is, the storage object identifier may
be empty); in this case, the OLE default CLSID for the file (usually
chosen based on the file's extension) will be used.
<DT>
<CODE>link</CODE>
<DD>
Only destinations that are single elements in the same RTF output file.
<DT>
<CODE>table</CODE>
<DT>
<CODE>table-part</CODE>
<DT>
<CODE>table-column</CODE>
<DD>
The table-auto-width feature isn't properly supported:
it's not really possible in RTF.
<DT>
<CODE>table-row</CODE>
<DT>
<CODE>table-cell</CODE>
<DT>
<CODE>table-border</CODE>
<DT>
math flow objects
<DD>
These are converted into Word EQ fields.  The Word EQ feature is not
powerful enough to do a really good job.  The mark flow object class
is particularily problematic, because there is no way automatically to
compute an appropriate position for the contents of the over-mark and
under-mark areas; however, some <A HREF="#superscript-height">additional
characteristics</A> are provided that allow the positioning to be
explicitly specified.
</DL>
<P>
Many DSSSL characteristics cannot be implemented in RTF.
The backend does the best it can.
<P>
In order to get correct page numbers in Microsoft Word, type the
following after opening the document:
<ol>
<li>CTRL+END
<li>CTRL+A
<li>F9
</ol>
<P>
In Word Viewer 97, you must instead do:
<ol>
<li>CTRL+END
<li>ALT
<li>V
<li>N
<li>ALT
<li>V
<li>P
</ol>
Page numbers also get updated automatically when you print.
<P>
The RTF backend supports some additional characteristics.  To
use a characteristic named here as <CODE><VAR>C</VAR></CODE>, declare
it using <CODE>declare-characteristic</CODE> with the public
identifier:
<PRE>
"UNREGISTERED::James Clark//Characteristic::<VAR>C</VAR>"
</PRE>
<DL>
<DT>
<CODE>heading-level</CODE>
<DD>
Value is an integer.  It applies to paragraph flow objects.  If the
value is between 1 and 9, then the paragraph is output as a header of
this level, otherwise it is output as body text.  Using this
characteristic allows Word to provide useful outline views and a
document map.  (Note that Word's handling of document maps for RTF
documents is buggy: if you load an RTF document, and the previous
document was using the Online Layout view, then RTF will attempt to
guess what paragraphs are headings, which it will almost always do
wrong.  To avoid this, switch to the Normal view before loading an RTF
document.)
The initial value is <CODE>0</CODE>
<DT>
<CODE>page-number-format</CODE>
<DD>
Value is a string as for
format-number procedure.  This controls the format of the number used
by page-number-sosofo and current-page-number-sosofo for references to
pages in the simple-page-sequence.  The initial value is <CODE>"1"</CODE>.
It applies to simple-page-sequence flow objects.
<DT>
<CODE>page-number-restart?</CODE>
<DD>
Value is a boolean.  If true, then
for the purposes of page-number-sosofo and current-page-number-sosofo,
the page numbers for this simple-page-sequence will restart from 1.
The initial value is <CODE>#f</CODE>.
It applies to simple-page-sequence flow objects.
<DT>
<CODE>page-n-columns</CODE>
<DD>
Value is a strictly positive integer, specifying the number of columns.
The initial value is 1.
It applies to simple-page-sequence flow objects.
<DT>
<CODE>page-column-sep</CODE>
<DD>
Value is a length, specifying the separation between columns.
The initial value is <CODE>.5in</CODE>.
It applies to simple-page-sequence flow objects.
<DT>
<CODE>page-balance-columns?</CODE>
<DD>
Value is a boolean.  If true, the columns on the final page of the
page-sequence should be balanced.  The initial value is <CODE>#f</CODE>.
It applies to simple-page-sequence flow objects.
<DT>
<CODE><A NAME="superscript-height">superscript-height</A></CODE>
<DD>
Value is a length.  Specifies the height of the baseline of a
superscript above its parent's baseline.  It applies to superscript
and script flow objects.
<DT>
<CODE>subscript-depth</CODE>
<DD>
Value is a length.  Specifies the depth of the baseline of a subscript
below its parent's baseline.  It applies to subscript and script flow
objects.
<DT>
<CODE>over-mark-height</CODE>
<DD>
Value is a length.  Specifies the height of the baseline of the
contents of the over-mark area of a mark flow object above the
baseline of the contents of the main area.  It also controls the
height of the contents of the mid-sup area of the script flow object.
It applies to mark and script flow objects.
<DT>
<CODE>under-mark-depth</CODE>
<DD>
Value is a length.  Specifies the depth of the baseline of the
contents of the under-mark area of a mark flow object below the
baseline of the contents of the main area.  It also controls the depth
of the contents of the mid-sub area of the script flow object.  It
applies to mark and script flow objects.
<DT>
<CODE>grid-row-sep</CODE>
<DD>
Value is a length.
Specifies the separation between rows of a grid flow object.
<DT>
<CODE>grid-column-sep</CODE>
<DD>
Value is a length.
Specifies the separation between columns of a grid flow object.
</DL>

<h3><A NAME=backend-fot>XML Flow Object Tree backend</A></h3>
<p>
The DTD for the XML generated is in <CODE>dsssl/fot.dtd</CODE>.
<p>
Characteristics declared with <code>declare-characteristic</code> are
not reported.
<p>
Flow objects of classes declared with <code>declare-flow-object</code>
are not reported.

<h2><A NAME=source>Reading the Jade Sources</A></h2>
<P>
Start with the following headers:
<PRE>
grove/Node.h
style/FOTBuilder.h
style/StyleEngine.h
</PRE>

<h2><A NAME=bugs>Reporting Bugs in Jade</A></h2>
<P>
If you find a bug in Jade, please take the time to report it.  If Jade
crashes on any input whatever, that's a bug and I want to hear about
it.  If Jade fails to process a specification that conforms to the
DSSSL standard in the manner required by the DSSSL standard in a way
that is not documented here as a current limitation nor is documented
as an error in the proposed <A
HREF="http://www.ornl.gov/sgml/wg8/document/1883.htm">Technical
Corrigendum</A> to the DSSSL standard, that's a bug and I want to hear
about it.
<p>
Please report bugs by email to me, <A
href="mailto:jjc@jclark.com"><CODE>jjc@jclark.com</CODE></A>.  Do not
post them to comp.text.sgml nor to the sp-prog mailing list nor to the DSSSList
mailing list.
<p>
I do not want to get bug reports about documented limitations, so
please read the list of limitations carefully.  However, feel free to
let me know which of the current limitations you would most like to
see addressed.
<p>
I also at this stage do not want to hear about bugs in your C++
compiler that prevent it from compiling Jade: if your compiler refuses
to compile Jade, I want to hear about it only if
<UL>
<LI>
it is because the Jade source code fails to conform to the current
ANSI C++ draft in some way, or
<LI>
you have a clean, simple and portable workaround for your compiler's
bug.
</UL>
<P>
Before reporting a bug, please check that your version is current.
<P>
<strong>The most important thing in reporting a bug is to include a
complete set of files on which I can run jade and reproduce the
problem</strong>.  Include all DTDs that you use, whether or not they
are standard.  Also tell me what command line I should use, and what
is incorrect about the behaviour of jade.  If the files are large
package them up as a tar or zip file and upload them to
<SAMP>ftp://ftp.jclark.com/incoming</SAMP>.
<P>
It is useful if you have a fix for a bug, but please don't delay
sending in the bug while you work on a fix and don't send in a fix
without giving me the files to reproduce the bug it fixes.

<h2><A NAME=contribute>Contributing to Jade</A></h2>
<p>
Here are some ways you can contribute to Jade:
<UL>
<LI>
Send in good bug reports.
<LI>
Write another backend.  I would like to see the following backends:
<UL>
<LI>
groff/troff
<LI>
a formatter that can produce output using
<UL>
<LI>
PDF
<LI>
Windows GDI
<LI>
Plain text
</UL>
</UL>
<LI>
Write some more documentation.
<LI>
Create a test suite.
</UL>
<p>
<ADDRESS>
<A HREF="mailto:jjc@jclark.com">James Clark</A>
</ADDRESS>
